Skip to content

docs: formal Bayesian specification of autofit.graphical (EP review phase 2)#1334

Merged
Jammy2211 merged 2 commits into
mainfrom
feature/ep-graphical-docs
Jul 10, 2026
Merged

docs: formal Bayesian specification of autofit.graphical (EP review phase 2)#1334
Jammy2211 merged 2 commits into
mainfrom
feature/ep-graphical-docs

Conversation

@Jammy2211

Copy link
Copy Markdown
Collaborator

Summary

Phase 2 of the EP framework review (#1333; statistics audit #1332): package-level documentation stating the exact Bayesian machinery autofit/graphical implements, in formal equations, each anchored to the implementing class/method so code can be verified against the stated math line-by-line. Adds autofit/graphical/README.md (the specification) plus targeted docstring upgrades at the load-bearing statistical points (update_factor_mean_field, MeanField.kl, TransformedMessage composition convention, AbstractMessage.project), and fixes one incorrect docstring equation (#1332 F5).

API Changes

None — documentation only. No signatures, symbols or behaviour changed.
See full details below.

Test Plan

  • pytest test_autofit/ full suite in the task worktree (counts in validation checklist)
  • pytest test_autofit/graphical/ test_autofit/messages/ — 200 passed (pre-ship)
  • Proofread README equations against source anchors (reviewer)
Full API Changes (for automation & release notes)

Removed

  • None.

Added

  • None (documentation only: new autofit/graphical/README.md; docstrings on existing methods).

Migration

  • None required.

Validation checklist (--auto run)

🤖 Generated with Claude Code

…ical docstrings)

- autofit/graphical/README.md (new): the mathematics as implemented —
  factor-graph model, exponential-family mean field, the EP step
  (cavity / tilted / moment-matching projection / damped division as
  natural-parameter EMA), the three factor-optimiser paths, convergence
  criterion + KL direction contract, evidence decomposition,
  deterministic-variable mechanisms, parallel-EP semantics; each
  equation anchored to its implementing class/method.
- MeanField.update_factor_mean_field: damped-update equations, delta
  semantics, invalid-projection fallback.
- MeanField.kl: KL direction contract (m.kl(other) == KL(m||other)).
- FactorApproximation: fix damped-update docstring error
  ((q_a^f)^(1-d) -> (q_a)^(1-d)).
- composed_transform.py: module docstring stating the transform
  composition-order convention (innermost-first storage; reversal
  asymmetry) with a worked UniformPrior trace; direction notes on
  _transform/_inverse_transform; validity condition on
  TransformedMessage.kl.
- AbstractMessage.project: moment-matching projection equations.

EP framework review phase 2 (#1333); audit findings context in #1332.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ests

- autofit/graphical/README.md: new §8 'The lowering contract
  (declarative → graph)' — every declarative concept and what it lowers
  to, with invariants (compound priors add no variables; factor_out not
  reachable by design; PriorFactor exact-hooks gap noted → #1337/#1338).
- AGENTS.md: the EP seam rule — inner-layer capability lands in the
  same PR as its declarative expression or an explicit 'not exposed'
  entry, plus a seam test.
- test_autofit/graphical/test_declarative_deterministic.py: replaced
  the commented-out PR #1153 illustration with 4 working seam tests
  pinning the explicit compound-prior lowering (no new variables,
  graph shape, in-factor realisation, shared-variable connectivity).
  The model.<property> sugar remains deliberately reverted (be64117).

EP review seam recommendations (#1330 wrap-up discussion); Phase 5
recommendation A item 2 delivered independently of the #1336 decision.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@Jammy2211

Copy link
Copy Markdown
Collaborator Author

Scope addition (commit 39eaf55) — the seam-contract work from the two-layer architecture discussion on the review:

The PR is no longer strictly docs-only (one test file), but still zero runtime-behaviour change. Full suite on the branch: 1425 passed / 14 skipped (1422 baseline + 4 seam tests − 1 replaced no-op).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pending-release PR queued for the next release build

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant